<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Nested transactions</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="transapp.html" title="Chapter 11.  Berkeley DB Transactional Data Store Applications" />
    <link rel="prev" href="transapp_cursor.html" title="Transactional cursors" />
    <link rel="next" href="transapp_admin.html" title="Environment infrastructure" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Nested transactions</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="transapp_cursor.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 11. 
		Berkeley DB Transactional Data Store Applications
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="transapp_admin.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="transapp_nested"></a>Nested transactions</h2>
          </div>
        </div>
      </div>
      <p>Berkeley DB provides support for nested transactions.  Nested transactions
allow an application to decompose a large or long-running transaction
into smaller units that may be independently aborted.</p>
      <p>Normally, when beginning a transaction, the application will pass a NULL
value for the parent argument to <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV-&gt;txn_begin()</a>.  If, however, the
parent argument is a <a href="../api_reference/C/txn.html" class="olink">TXN</a> handle, the newly created transaction
will be treated as a nested transaction within the parent.  Transactions
may nest arbitrarily deeply.  For the purposes of this discussion,
transactions created with a parent identifier will be called
<span class="emphasis"><em>child transactions</em></span>.</p>
      <p>Once a transaction becomes a parent, as long as any of its child
transactions are unresolved (that is, they have neither committed nor
aborted), the parent may not issue any Berkeley DB calls except to begin more
child transactions, or to commit or abort.  For example, it may not
issue any access method or cursor calls.  After all of a parent's
children have committed or aborted, the parent may again request
operations on its own behalf.</p>
      <p>The semantics of nested transactions are as follows.  When a child
transaction is begun, it inherits all the locks of its parent.  This
means that the child will never block waiting on a lock held by its
parent.  Further, locks held by two children of the same parent will
also conflict.  To make this concrete, consider the following set of
transactions and lock acquisitions.</p>
      <p>Transaction T1 is the parent transaction.  It acquires a write lock on
item A and then begins two child transactions: C1 and C2.  C1 also wants
to acquire a write lock on A; this succeeds.  If C2 attempts to acquire
a write lock on A, it will block until C1 releases the lock, at which
point it will succeed.  Now, let's say that C1 acquires a write lock on
B.  If C2 now attempts to obtain a lock on B, it will block.  However,
let's now assume that C1 commits.  Its locks are anti-inherited, which
means they are given to T1, so T1 will now hold a lock on B.  At this
point, C2 would be unblocked and would then acquire a lock on B.</p>
      <p>Child transactions are entirely subservient to their parent transaction.
They may abort, undoing their operations regardless of the eventual fate
of the parent.  However, even if a child transaction commits, if its
parent transaction is eventually aborted, the child's changes are undone
and the child's transaction is effectively aborted.  Any child
transactions that are not yet resolved when the parent commits or aborts
are resolved based on the parent's resolution -- committing if the
parent commits and aborting if the parent aborts.  Any child
transactions that are not yet resolved when the parent prepares are also
prepared.</p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="transapp_cursor.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="transapp.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="transapp_admin.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Transactional cursors </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Environment infrastructure</td>
        </tr>
      </table>
    </div>
  </body>
</html>
